Loading TOC...

PUT /v1/alert/rules/{name}

Summary

Install an alerting rule under the given name.

URL Parameters
database? Perform this operation on the named content database instead of the default content database associated with the REST API instance. Using an alternative database requires the "eval-in" privilege; for details, see Security Requirements in the REST Application Developer's Guide.
format? The content type of the data in the request body. The format parameter value is only used if the Content-type header is not set or is not set to a MIME type mapped to XML or JSON.
Request Headers
Content-type The MIME type of the data in the request body, either application/json or application/xml.

Response

Upon success, MarkLogic Server returns status 201 (Created) or 204 (Updated), depending on whether or not the named rule already exists.

If the payload is invalid, MarkLogic Server responds with status 400 by default. If no rule matching {name} is installed, MarkLogic Server returns status code 404.

If the Alerting API is not enabled, MarkLogic Server returns status 403.

Required Privileges

This operation requires the rest-writer role, or the following privilege:

http://marklogic.com/xdmp/privileges/rest-writer

Usage Notes

After installing one or more rules, use the /alert/match service to poll for documents that match rules. This allows you to create an alerting application using a pull model. To use a push model, you must use an XQuery implementation in MarkLogic Server, as described in Creating Alerting Applications in the Search Developer's Guide.

For more information, see Defining an Alerting Rule in the REST Application Developer's Guide.

Example

$ cat ./rule.xml
<rapi:rule xmlns:rapi="http://marklogic.com/rest-api">
  <rapi:name>example</rapi:name>
  <rapi:description>An example rule.</rapi:description>
  <search:search xmlns:search="http://marklogic.com/appservices/search">
    <search:qtext>xdmp</search:qtext>
    <search:options>
      <search:term>
        <search:term-option>case-sensitive</search:term-option>
      </search:term>
    </search:options>
  </search:search>
  <rapi:rule-metadata>
    <author>me</author>
  </rapi:rule-metadata>
</rapi:rule>

$ curl --anyauth --user user:password -X PUT -d @./rule.xml -i \
    -H "Content-type: application/xml" \
    http://localhost:8000/v1/alert/rules/example

==> The rule defined in the file ./rule.xml is installed under the
    name "example". MarkLogic Server responds with output similar
    to the following:

HTTP/1.1 204 Updated
Server: MarkLogic
Content-Length: 0
Connection: Keep-Alive
Keep-Alive: timeout=5

Example

$ curl --anyauth --user user:password -X PUT -d @./rule.xml -i \
    -H "Content-type: application/xml" \
    http://localhost:8000/v1/alert/rules/json-example

==> The rule defined in the file ./rule.xml is installed under the
    name "example". MarkLogic Server responds with output similar
    to the following:

HTTP/1.1 201 Created
Location:
Server: MarkLogic
Content-Length: 0
Connection: Keep-Alive
Keep-Alive: timeout=5

$ cat ./rule.json
{ "rule": {
  "name" : "json-example",
  "search" : {
    "qtext" : "xdmp",
    "options" : { "term" : { "term-option" : "case-sensitive" } }
  },
  "description": "A JSON example rule.",
  "rule-metadata" : { "author" : "me" }
}}

Stack Overflow iconStack Overflow: Get the most useful answers to questions from the MarkLogic community, or ask your own question.